Inside Macintosh: QuickTime /

Chapter 3 - Image Compression Manager / Image Compression Manager Reference

Image Compression Manager Functions / Working With Pictures and PICT Files

FCompressPictureFile

The FCompressPictureFile function compresses a single-frame image stored as a picture file (PICT file) and places the result in another picture file.

pascal OSErr FCompressPictureFile (short srcRefNum, 
                           short dstRefNum, short colorDepth, 
                           CTabHandle clut, CodecQ quality, 
                           short doDither, 
                           short compressAgain,
                           ProgressProcRecordPtr progressProc,
                           CodecType cType,
                           CompressorComponent codec);

srcRefNum

Specifies a file reference number for the source PICT file.

dstRefNum

Specifies a file reference number for the destination PICT file. Note that the compressor overwrites the contents of the file referred to by dstRefNum. You must open this file with write permissions. The destination file may be the same as the source file specified by the srcRefNum parameter.

colorDepth

Specifies the depth at which the image is to be compressed. If you set this parameter to 0, the Image Compression Manager determines the appropriate value for the source image. Values of 1, 2, 4, 8, 16, 24, and 32 indicate the number of bits per pixel for color images. Values of 34, 36, and 40 indicate 2-bit, 4-bit, and 8-bit grayscale, respectively, for grayscale images. Your program can determine which depths are supported by a given compressor by examining the compressor capability structure returned by the GetCodecInfo function (see "Getting Information About Compressor Components," which begins on page 3-62, for more information).

clut

Contains a handle to a custom color lookup table. Your program may use this parameter to indicate a custom color lookup table to be used with this image. If the value of the colorDepth parameter is less than or equal to 8 and the custom color lookup table is different from that of the source pixel map (that is, the ctSeed field values differ in the two pixel maps), the compressor remaps the colors of the image to the custom colors. If you set the colorDepth parameter to 16, 24, or 32, the compressor stores the custom color table with the compressed image. The compressor may use the table to specify the best colors to use when displaying the image at lower bit depths. The compressor ignores the clut parameter when colorDepth is set to 33, 34, 36, or 40. If you set this parameter to nil, the compressor uses the color lookup table from the source pixel map.

quality

Specifies the desired compressed image quality. See "Compression Quality Constants" on page 3-57 for available values.

doDither

Indicates whether to dither the image. Use this parameter to indicate whether you want the image to be dithered when it is displayed on a lower-resolution screen. The following constants are available:

defaultDither

Indicates that the dithering in the source file is to be respected.

forceDither

Indicates that the specified image should be dithered whether the source uses dithering or not.

suppressDither

Indicates that dithering should not be used in any case. The ability to suppress dithering can be useful if, for example, you have a 32-bit, color JPEG image drawn into an 8-bit buffer with a custom color table from the image. In that case, dithering would not be necessary and probably not desirable, particularly if the buffer were to be compressed with the graphics compressor.

compressAgain

Indicates whether to recompress compressed image data in the picture. Use this parameter to control whether any compressed image data that is in the source picture should be decompressed and then recompressed using the current parameters. Set the value of this parameter to true to recompress such data. Set the value of this parameter to false to leave the data as it is. Note that recompressing the data may have undesirable side effects, including image quality degradation.

progressProc

Points to a progress function structure. During the compression operation, the compressor may occasionally call a function you provide in order to report its progress (see "Progress Functions" on page 3-146 for more information about progress functions). If you have not provided a progress function, set this parameter to nil. If you pass a value of -1, you obtain a standard progress function.

cType

Specifies a compressor type. You must set this parameter to a
valid compressor type (see Table 3-3 on page 3-64 for a list of the available compressor types). If the value passed in is 0, or 'raw ' and the source picture is compressed, the destination picture is created as an uncompressed picture and does not require QuickTime to be displayed.

codec

Contains a compressor identifier. Specify a particular compressor by setting this parameter to its compressor identifier. Alternatively, you may use one of the special identifiers:

anyCodec

Choose the first compressor of the specified type

bestSpeedCodec

Choose the fastest compressor of the specified type

bestFidelityCodec

Choose the most accurate compressor of the specified type

bestCompressionCodec

Choose the compressor that produces the smallest resulting data

You can also specify a component instance. This may be useful if you have previously set some parameter on a specific instance of a codec field and want to make sure that the specified instance is used for that operation.

DESCRIPTION

The FCompressPicture function compresses only image data. Any other types of data in the file, such as text, graphics primitives, and previously compressed images, are not modified in any way and are passed through to the destination picture file.

This function supports parameters governing image quality, compressor type, image depth, custom color tables, and dithering.

RESULT CODES

noErr	0	No error
paramErr	-50	Invalid parameter specified
memFullErr	-108	Not enough memory available
noCodecErr	-8961	The Image Compression Manager could not find the specified compressor
codecAbortErr	-8967	Operation aborted by the progress function

File Manager errors

SEE ALSO

If you do not need such a high degree of control over the compression operation, use the CompressPictureFile function, described on page 3-88.